---
type: flow
title: Refund Flow
description: How money goes back — from a support decision in the Backoffice to a confirmed provider refund and its event.
tags: [flow]
timestamp: {{DATE}}
---
<!-- ✂ docujoint template sample — replace with your own content, then delete this comment. -->
# Refund Flow

## Overview
Started by a [Support Agent](</Actors/Support Agent.md>) on the
[Orders Dashboard](</Apps/Backoffice/Pages/Orders Dashboard.md>).
[Payments Service](</Services/Payments Service.md>) calls
[Stripe](</Services/Stripe.md>) refunds, records a `refund` row in
[payment_attempts](</Data/main/Tables/payment_attempts.md>), moves the
[orders](</Data/main/Tables/orders.md>) row to `refunded` (see
[order-status](</Data/main/Enums/order-status.md>)), and publishes
[order-refunded](</Events/order-refunded.md>).

## Map
```mermaid
sequenceDiagram
  participant Agent as Support Agent
  participant BO as Backoffice
  participant Pay as Payments Service
  participant S as Stripe
  Agent->>BO: confirm refund + reason
  BO->>Pay: POST /refunds
  Pay->>S: refund request
  S-->>Pay: confirmed or rejected
  Pay-->>BO: outcome + attempt recorded
```

## Status transitions
What a refund does to the order's lifecycle — the states are the canonical
values of [order-status](</Data/main/Enums/order-status.md>), so this diagram
and the enum document must agree:

```mermaid
stateDiagram-v2
  [*] --> placed
  placed --> fulfilled : items delivered
  placed --> cancelled : cancelled before fulfilment
  fulfilled --> refunded : refund confirmed (this flow)
  cancelled --> refunded : money returned
  refunded --> [*]
```

## Shared steps
1. Agent confirms the refund and a reason code in the order detail.
2. Payments Service validates the order is refundable (status `fulfilled` or `cancelled` pending money).
3. Provider refund is requested — paths diverge on the outcome.

## Features

## Scenarios

## Open questions

## Transitions
| To | When |
|----|------|
| Order refunded | The provider confirms the refund — the orders row moves to `refunded` and order-refunded is published |
| Refund rejected | The provider rejects the refund — the attempt is recorded and the order keeps its status |